home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / mimelib / protocol.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-14  |  11.4 KB  |  269 lines
  1. //=============================================================================
  2. // File:       proto_un.h
  3. // Contents:   Declarations for DwClientProtocol
  4. // Maintainer: Doug Sauder <dwsauder@fwb.gulf.net>
  5. // WWW:        http://www.fwb.gulf.net/~dwsauder/mimepp.html
  6. //
  7. // Copyright (c) 1996, 1997 Douglas W. Sauder
  8. // All rights reserved.
  9. // 
  10. // IN NO EVENT SHALL DOUGLAS W. SAUDER BE LIABLE TO ANY PARTY FOR DIRECT,
  11. // INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
  12. // THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF DOUGLAS W. SAUDER
  13. // HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. //
  15. // DOUGLAS W. SAUDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT
  16. // NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  17. // PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS"
  18. // BASIS, AND DOUGLAS W. SAUDER HAS NO OBLIGATION TO PROVIDE MAINTENANCE,
  19. // SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. //
  21. //=============================================================================
  22.  
  23. #ifndef DW_PROTOCOL_H
  24. #define DW_PROTOCOL_H
  25.  
  26. #include <sys/types.h>
  27. #include <sys/socket.h>
  28. #include <netinet/in.h>
  29.  
  30. #ifndef DW_CONFIG_H
  31. #include <mimelib/config.h>
  32. #endif
  33.  
  34. #ifndef DW_STRING_H
  35. #include <mimelib/string.h>
  36. #endif
  37.  
  38.  
  39. class DwObserver {
  40. public:
  41.     virtual void Notify()=0;
  42. };
  43.  
  44.  
  45. //=============================================================================
  46. //+ Name DwProtocolClient -- Base class for all protocol clients
  47. //+ Description
  48. //. {\tt DwProtocolClient} is the base class for other classes that implement
  49. //. specific protocols, such as SMTP, POP, and NNTP.  {\tt DwProtocolClient}
  50. //. serves two purposes.  First, It combines operations common to all its
  51. //. derived classes, such as opening a TCP connection to the server.  Second,
  52. //. it provides a platform-independent interface to the network services
  53. //. required by its subclasses.
  54. //.
  55. //. There are two separate implementations of {\tt DwProtocolClient}: one for
  56. //. Berkeley sockets under UNIX, and one for Winsock under Win32.  The
  57. //. interface is the same for both implementations, thus providing platform
  58. //. independence.
  59. //.
  60. //. There are two platform-specific details that you should be aware of.
  61. //. First, if you are writing a UNIX program, you should be sure to handle
  62. //. the SIGPIPE signal.  This signal is raised when a program tries to write
  63. //. to a TCP connection that was shutdown by the remote host.  The default
  64. //. action for this signal is to terminate the program.  To prevent this
  65. //. from happening in your program, you should either catch the signal or
  66. //. tell the operating system to ignore it.  Second, if you are writing a
  67. //. Win32 application for Windows NT or Windows95, you should be aware of
  68. //. the fact that the constructor calls the Winsock function
  69. //. {\tt WSAStartup()} to initialize the Winsock DLL.  (The destructor
  70. //. calls {\tt WSACleanup()}.)  Because it is possible for {\tt WSAStartup()}
  71. //. to fail, it is also possible that the constructor may fail.  To verify
  72. //. that the constructor has succeeded, call the member function
  73. //. {\tt LastError()} and check that it returns zero.
  74. //.
  75. //. To open a connection to a server, call {\tt Open()} with the server name
  76. //. and TCP port number as arguments.  {\tt Open()} is declared virtual;
  77. //. derived classes may override this member function.  {\tt Open()} may fail,
  78. //. so you should check the return value to verify that it succeeded.  To close
  79. //. the connection, call {\tt Close()}.  To check if a connection is open,
  80. //. call {\tt IsOpen()}.  {\tt IsOpen()} returns a value that indicates whether
  81. //. or not a call to {\tt Open()} was successful; it will not detect failure
  82. //. in the network or a close operation by the remote host.
  83. //.
  84. //. {\tt DwProtocolClient} sets a timeout on receive operations on the TCP
  85. //. connection.  The default value of the timeout period is 90 seconds.  To
  86. //. change the default value, call {\tt SetReceiveTimeout()} and pass the
  87. //. new value as an argument.
  88. //.
  89. //. Whenever {\tt DwProtocolClient} cannot complete an operation, it is because
  90. //. an error has occurred.  Most member functions indicate that an error has
  91. //. occurred via their return values.  For most member functions, a return
  92. //. value of -1 indicates an error.  To get the specific error that has
  93. //. occurred, call {\tt LastError()}, which returns either the system error
  94. //. code or a MIME++ defined error code.  To get a text string that describes
  95. //. the error, call {\tt LastErrorStr()}.
  96. //.
  97. //. Some errors are also considered "failures."  A failure occurs when an
  98. //. operation cannot be completed because of conditions external to the
  99. //. program.  For example, a failure occurs when the network is down or
  100. //. when an application's user enters bad input.  Errors that occur because
  101. //. of programmer error are not considered failures.  If an error occurs,
  102. //. you should call {\tt LastError()} to determine the error, but you should
  103. //. also call {\tt LastFailure()} to determine if a failure occurred.  In
  104. //. interactive applications, failures should always be reported to the
  105. //. application's user.  To get a text string that describes a failure,
  106. //. call {\tt LastFailureStr()}.
  107. //.
  108. //. It is possible to translate the error and failure message strings to a
  109. //. language other than English.  To do this, you may override the virtual
  110. //. function {\tt HandleError()}.
  111. //=============================================================================
  112.  
  113. //+ Noentry mFailureCode mFailureStr mErrorCode mErrorStr mLastCommand
  114. //+ Noentry mIsDllOpen mIsOpen mSocket mPort mServerName mReceiveTimeout
  115.  
  116.  
  117. class DwProtocolClient {
  118.  
  119. public:
  120.  
  121.     enum Failure {
  122.         kFailNoFailure      = 0, // No failure
  123.         kFailNoWinsock      = 1, // A usable Winsock DLL could not be found
  124.         kFailNetDown        = 2, // The network is down
  125.         kFailHostNotFound   = 3, // The server was not found
  126.         kFailConnReset      = 4, // The connection was reset
  127.         kFailNetUnreachable = 5, // The network is unreachable
  128.         kFailTimedOut       = 6, // Timed out while waiting for an operation
  129.                                  // to complete
  130.         kFailConnDropped    = 7,
  131.         kFailConnRefused    = 8,
  132.         kFailNoResources    = 9
  133.     };
  134.     //. Enumerated values for failures.
  135.  
  136.     enum Error {
  137.         kErrNoError = 0,
  138.         kErrUnknownError = 0x4000,
  139.         kErrBadParameter = 0x4001,
  140.         kErrBadUsage     = 0x4002,
  141.         kErrNoWinsock    = 0x4003,  // Win32
  142.         kErrHostNotFound = 0x5000,  // UNIX
  143.         kErrTryAgain     = 0x5001,  // UNIX
  144.         kErrNoRecovery   = 0x5002,  // UNIX
  145.         kErrNoData       = 0x5003,  // UNIX
  146.         kErrNoAddress    = 0x5004   // UNIX
  147.     };
  148.     //. MIME++-defined error codes.
  149.  
  150. protected:
  151.  
  152.     DwProtocolClient();
  153.     //. Initializes the {\tt DwProtocolClient} object.
  154.     //. In a Win32 environment, this constructor calls {\tt WSAStartup()}
  155.     //. to initialize the Winsock DLL. To verify that the DLL was initialized
  156.     //. successfully, call the member function {\tt LastError()} and verify
  157.     //. that it returns zero.
  158.  
  159. public:
  160.  
  161.     virtual ~DwProtocolClient();
  162.     //. Frees the resources used by this object.
  163.     //. In a Win32 environment, the destructor calls {\tt WSACleanup()}.
  164.  
  165.     virtual int Open(const char* aServer, DwUint16 aPort);
  166.     //. Opens a TCP connection to the server {\tt aServer} at port {\tt aPort}.
  167.     //. {\tt aServer} may be either a host name, such as "smtp.acme.com" or an
  168.     //. IP number in dotted decimal format, such as "147.81.64.59".  If the
  169.     //. connection attempt succeeds, {\tt Open()} returns 0; othewise, it
  170.     //. returns -1.  To determine what error occurred when the connection
  171.     //. attempt fails, call the member function {\tt LastError()}. To
  172.     //. determine if a failure also occurred, call the member function
  173.     //. {\tt LastFailure()}.
  174.  
  175.     DwBool IsOpen() const;
  176.     //. Returns true value if a connection to the server is open.
  177.     //. {\tt IsOpen()} will return a true value if a call to {\tt Open()} was
  178.     //. successful;  it will not detect failure in the network or a close
  179.     //. operation by the remote host.
  180.  
  181.     int Close();
  182.     //. Closes the connection to the server.  Returns 0 if successful, or
  183.     //. returns -1 if unsuccessful.
  184.  
  185.     int SetReceiveTimeout(int aSecs);
  186.     //. Changes the default timeout for receive operations on the socket to
  187.     //. {\tt aSecs} seconds.
  188.     //. The default value is 90 seconds.
  189.  
  190.     int LastCommand() const;
  191.     //. Returns an enumerated value indicating the last command sent to
  192.     //. the server. Enumerated values are defined in subclasses of
  193.     //. {\tt DwProtocolClient}.
  194.  
  195.     int LastFailure() const;
  196.     //. Returns an enumerated value indicating what failure last occurred.
  197.  
  198.     const char* LastFailureStr() const;
  199.     //. Returns a failure message string associated with the failure code
  200.     //. returned by {\tt LastFailure()}.
  201.  
  202.     int LastError() const;
  203.     //. Returns an error code for the last error that occurred.  Normally, the
  204.     //. error code returned is an error code returned by a system call;
  205.     //. {\tt DwProtocolClient} does no translation of error codes returned
  206.     //. by system calls.  In some cases, an error code defined by MIME++ may
  207.     //. returned to indicate improper use of the {\tt DwProtocolClient} class.
  208.  
  209.     const char* LastErrorStr() const;
  210.     //. Returns an error message string associated with the error code returned
  211.     //. by {\tt LastError()}.
  212.  
  213. protected:
  214.  
  215.     enum {
  216.         kWSAStartup=1,  // Win32
  217.         kgethostbyname,
  218.         ksocket,
  219.         ksetsockopt,
  220.         kconnect,
  221.         ksend,
  222.         krecv,
  223.         kclose,         // UNIX
  224.         kclosesocket,   // Win32
  225.         kselect
  226.     };
  227.     // Enumerated values that indicate the system call that detected
  228.     // an error
  229.  
  230.     DwBool      mIsDllOpen;
  231.     DwBool      mIsOpen;
  232.     int         mSocket;
  233.     DwUint16    mPort;
  234.     char*       mServerName;
  235.     int         mReceiveTimeout;
  236.     int         mLastCommand;
  237.     int         mFailureCode;
  238.     const char* mFailureStr;
  239.     int         mErrorCode;
  240.     const char* mErrorStr;
  241.  
  242.     virtual void HandleError(int aErrorCode, int aSystemCall);
  243.     //. Interprets error codes.  {\tt aErrorCode} is an error code,
  244.     //. which may be a system error code, or an error code defined by
  245.     //. {\tt DwProtocolClient}.  {\tt aSystemCall} is an enumerated value
  246.     //. defined by {\tt DwProtocolClient} that indicates the last system
  247.     //. call made, which should be the system call that set the error code.
  248.     //. {\tt HandleError()} sets values for {\tt mErrorStr},
  249.     //. {\tt mFailureCode}, and {\tt mFailureStr}.
  250.  
  251.     int PSend(const char* aBuf, int aBufLen);
  252.     //. Sends {\tt aBufLen} characters from the buffer {\tt aBuf}.  Returns
  253.     //. the number of characters sent.  If the number of characters sent
  254.     //. is less than the number of characters specified in {\tt aBufLen},
  255.     //. the caller should call {\tt LastError()} to determine what, if any,
  256.     //. error occurred.  To determine if a failure also occurred, call the
  257.     //. member function {\tt LastFailure()}.
  258.  
  259.     int PReceive(char* aBuf, int aBufSize);
  260.     //. Receives up to {\tt aBufSize} characters into the buffer {\tt aBuf}.
  261.     //. Returns the number of characters received.  If zero is returned, the
  262.     //. caller should call the member function {\tt LastError()} to determine
  263.     //. what, if any, error occurred. To determine if a failure also occurred,
  264.     //. call the member function {\tt LastFailure()}.
  265.  
  266. };
  267.  
  268. #endif
  269.